Tech Arsenal 1

home *** CD-ROM | disk | FTP | other *** search

/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-19 / quikcmd3.zip / BUZ.DOC < prev next >

Wrap

Text File | 1992-07-05 | 48KB | 987 lines

BUZ.EXE Version 1.10 completed in May 1992 ~* BUZ.EXE V1.10 Self-Indexing View/Print Utility for Text Files ~ By Dan Jincks (C) 1991, 92 All Rights Reserved. Copying and distribution of BUZ.EXE and BUZ.DOC are specifically limited to the terms and conditions contained in BUZ.DOC. Any copying and distribution of BUZ.EXE and BUZ.DOC, other then that which is specified in BUZ.DOC, requires the written permission of Dan Jincks, the author. Shareware distribution is specifically limited to the United States and Canada. Version 1.00 was not released to the general public. A number of copies were given out to individuals, and who knows who they gave them to, etc. To be sure that a distinction exits, the first true general release is called BUZ.EXE Version 1.10 rather than 1.00. It differs from Version 1.00 in that it is faster, smaller (but documentation got larger), and is more versatile in the print capabilities. It also has less bugs and more error trapping. The Quick Index left extension character was changed from a tilde to a right curly bracket. The Quick Index format was changed to make them faster and use less disk space. ~* Introduction --------------- BUZ was created to allow standard ASCII text files to serve as "Soft Publications". It automatically detects a "prepared for BUZ" text file and creates an index table "front end" as it begins running. Pressing an associated key in the displayed index table, sends the file viewer directly to that location within the text file. A single key press returns you to the index table, from any location in the file. The file viewer features full up/down scrolling abilities, by page or by line. The only preparation required to a convert a standard ASCII text file, is the simple insertion of tilde ~ characters at the beginning of lines to be referenced by the index table. BUZ automatically highlights lines in the text file that were marked by a tilde. Selective highlighting in the index table is available to aid in defining main and sub sections. BUZ can also be used to view ordinary ASCII text files. Files without index markers are presented without the index table. BUZ is also specially designed to allow indexed viewing of Basic, Assembler, Lisp, Pascal and "C" ASCII source code. In source code modes it auto-indexes with reference to any comment lines that begin in the first character position of a line. In addition to the viewer capabilities of BUZ, it contains considerable versatility for printing out text files. Printing can be sent to any LPT or COM port, or to a file. Any ASCII file can easily be completely or partially printed out. Partial printout definition is set up to bear relation to the position in the file as it is being viewed. You can easily print out just that portion of a large text file that you need. Automatic headers and page breaks, with user defined titles, are available for any printing task. Page definitions are automatically created by how you specify each printout, so there is no need to "printer-page format" any text files that will be printed by BUZ. If you need a text file "printer-page formatted" for some reason, BUZ can do that for you as well - in seconds. Since BUZ can handle extremely large text files, partial print-to-file techniques can quickly break up unwieldy files for loading into limited capacity text editors. Custom indentation, page lengths, and line lengths are supported as well. Considerable file information is also presented and updated by option settings. ~ Requirements, Statistics and General Information --------------------------------------------------- Requirements: IBM PC Compatible Computer with 256k of available free memory. MS-DOS or PC-DOS 3.0 or later. Display adapter: Any that can display 80 character X 25 line text screens. (Mono, Herc, CGA, EGA, VGA) For formatted printouts: Any printer with at least 80 character/line capabilities Statistics and General Information: Maximum size text file: 32,716 lines (typically well over 1 megabyte) Maximum number of Index entries in a file: 360 Speed: Initial startup varies, depending on the system and size of the file. Capable of creating an associated Quick Index file to reduce startup time for individual files. Once the initial startup has completed, file access is virtually instantaneous for any size file located on hard drive systems. Type of viewer: Reads directly from disk files, will not alter the file. Highly disk oriented, so the best performance is on a hard drive. Types of files that can be viewed: Standard ASCII text, "Index Prepared" Standard ASCII text, ASCII source code. Source Programming Language of BUZ.EXE: Microsoft (tm) BASIC Author of BUZ.EXE and BUZ.DOC: Dan Jincks HCR 77, Box 155A Annapolis, MO 63620 USA Type of distribution allowed: As Shareware in USA and Canada only. Availability of source code: Not generally available - Contact the Author. ~ Command line Syntax for using BUZ.EXE ---------------------------------------- Usage: BUZ [path]filename [/MSB | /C | /AL | /PAS] [/M | /AC] [/LS] BUZ or BUZ /? for syntax filename - The filename of an ASCII file to be viewed by BUZ. It must be ASCII text, free of non-standard control codes. BUZ can handle any size file up to 32,716 lines long. /MSB - Causes BUZ to use the ' single quote character for creating its index for the file being viewed. The single quote is typically used for comments in Microsoft BASIC (and Quick BASIC source code. /C - The / slash character is used for indexing - used for comment lines in "C" source code. /AL - The ; semicolon character is used for indexing - used for comment lines in Assembler and Lisp source code. /PAS - The { left curly bracket character is used for indexing - used for comment lines in Pascal source code. Note: By default, BUZ uses the ~ tilde character for creating its index. No matter which character is specified, it must be the very first character in a line, without any leading spaces, to be recognized as an index marker. /M - Causes BUZ to display in Monochrome. /AC - Causes BUZ to display in an alternate color scheme. /LS - Causes BUZ to Leave the viewing Screen intact when you quit. When you quit while in the viewer, the current screen of information remains when you return to the DOS prompt. If you are in the index screen when you quit, a normal exit occurs. Examples: BUZ BUZ.DOC To view BUZ.DOC in the default index and color modes. BUZ BUZ.DOC /M To view BUZ.DOC in monochrome. BUZ C:\BASIC\PROGRAM.BAS /MSB /AC To view a Microsoft BASIC source code file named PROGRAM.BAS in the BASIC subdirectory using the alternate color scheme. BUZ BUZ.DOC /LS To view BUZ.DOC and leave your final view of it on the screen when you return to the DOS prompt. ~ Getting the Best Performance from BUZ ---------------------------------------- BUZ.EXE was designed to handle very large text files. The larger that a file is, the more likely it is that you may notice BUZ slowing down a bit. To get the best speed out of BUZ, certain factors can help considerably. 1. Be sure that the file being read is located on a hard drive. (Of course a RAM drive is even faster.) The performance of BUZ is greatly affected by disk access speed, so reading a file from a floppy disk is the surest way to reduce its overall performance. 2. If all of the lines in the file are 76 characters or shorter, the scrolling response speed is greatly increased, particularly when the text file is very large (over 8000 lines). 3. If the file is free of imbedded Form Feed and Tab characters, scrolling speed is slightly faster. 4. Creating a "BUZ Quick Index" file will greatly reduce the start up time for future viewings of any "indexed" text or source code files. All of the above are optional but are well worth the effort if the file is large and/or a slower computer/drive will be used to view the file. The "Printing Definition" screen can provide instant information about #2 and #3 considerations listed above. Start by viewing the file, then press "P" to get the printing screen. It reports the length of the longest line in the file, and if it contains any Form Feed or Tab characters. You do not need to print anything to view this screen. By printing-to-a-file you can create a duplicate file without Form Feed characters. If you set the "Tab #" before printing-to-a-file, Tab characters will be replaced by spaces (see the section about "Tab #"). Long lines however, will require you to use a text editor. BUZ cannot reformat or edit text files. After #2 and #3 are dealt with as you intend to, then create a BUZ Quick Index file if you can spare some disk space. See the "Quick Index" section. ~* Using the BUZ File Viewer ---------------------------- When BUZ reads a file it automatically determines whether index markers are present. If the file has been marked, you will see the index table being built as it reads the file. If BUZ cannot find a marker on the first screen page, it will display the message "Reading File" until it completes its initial start-up. (It will also display "Reading File" if it is reading a BUZ Quick Index file.) The length of time required by the start-up process is proportional to the length of the file that you are viewing. The longer the file, the longer the start-up time. Once the start-up is complete, BUZ can move around in the file very quickly if the file is on a hard drive. Floppy disk files will greatly increase the viewer access time. This is because the drive quits running after a short time and must restart when BUZ looks for a new location in the file. BUZ does not load any of the file into RAM. It only keeps records of locations in the file in RAM. This allows reading and moving around quickly in very large files (well over the basic DOS RAM limitations), but makes floppy disk performance sluggish. BUZ was designed primarily for hard drive systems and large text files, but will function fully on floppy drives - although much slower. The initial user interface screen and controls will depend on whether the file was indexed. If the file was indexed, you will begin with the "Index Page" screen(s). If the file was not indexed, you will begin at the top of the file or "Home" screen of the scrolling viewer. No matter which screen you are in, the very top line is for relevant information and the very bottom line lists your key press options. Look up to see what is happening. Look down to see what you can do. ~ The Index Screens -------------------- When a file is "prepared for BUZ", the initial user interface are the index page screens. They are an active index to jump directly to various places within the text file. This is the equivalent of the table of contents in a book. You will be presented with a list of subjects (sections) to choose from. All that is required, is to press the listed letter key to go directly to that place in the text file. If the index is longer than 18 sections, you can page through the index by using either Page Up - Page Down keys or by pressing the space bar. You may also go directly to the END or top (HOME) of the file, directly from the index. After pressing an index selection, you will begin viewing within the text file at the desired location. From there, the normal scrolling viewer is functioning. To return to the index from anywhere in the text file, just press the space bar. Once back at the index screens, you can jump directly to another location in the file as desired. ~ The Scrolling File Viewer ---------------------------- The scrolling file viewer provides full up-down file viewing capabilities. You can go up or down in the text file by one line at a time or one entire screen page at a time. Simply use the cursor keys, Page Up-Down keys, Home, or End keys to navigate. Three other optional actions are also available while using the scrolling file viewer: ~ Tab# ---------- By pressing the "T" key you can redefine the number of spaces that are substituted for any ^I tab characters in the file that you are viewing. The default is to use the DOS standard, 8 space expansion on 8 character intervals. For most files this is correct. Some text editors (most notably programming source code editors) allow custom definition of tab expansion. If the column alignments don't look correct, or there are excessive leading spaces in some lines, you may want to try redefining the tab expansion. This doesn't actually alter the original file, but will affect the appearance of the file on both the screen and any printouts. The effect of this tab setting has no interval definition. It merely substitutes a given number of spaces for each ^I tab character. This works fine for leading tabs, but not for mid-line tabs. Ideally text files should not contain ^I tabs, unless they conform to the DOS standard. The "Printing Definition Screen" has an alert that a file contains Tabs or Form Feed characters. Press "P" while in the file viewer to check that alert message, if you suspect that Tabs may be causing problems in a file. Note: The <T=Tab#> option does not appear as a listed option when the file viewer is entered from the index, but it is still available by pressing the "T" key. ~ Shell ----------- While using the BUZ file viewer, you can press the "S" key to "Shell" to the DOS command line. You are not actually quitting BUZ, but freezing its actions and place while allowing you to return to DOS. BUZ and your place in the file being viewed are still in your computers memory. When you type "EXIT" at the DOS command line, you will return to BUZ in the place that you were before you shelled. The shell feature was included to allow you to "hold your place" and do something else - and then pick up where you left off. A use for this might be to try something on your computer that you are reading documentation about. Another use might be to hold your place and look up your appointments or a phone number. You can even run BUZ a second time on another file. When you shell, BUZ will report how much free memory is remaining to run other programs. Since BUZ is still in memory, you will have less available. To regain all of your free memory again you must "Quit" BUZ, rather than use the shell option. BUZ records the drive and directory that you were in when you used Shell. You can freely change drives and directories, while back at the DOS command line, for whatever you need to do. When you enter the EXIT command to return to BUZ, it automatically returns to its starting drive and directory. Shell cannot be used to change the directory that BUZ is currently functioning within. ~ Print ----------- By pressing the "P" key you bring up the printing definition screen. This screen provides information and choices that allow you to print part or all of the file that you are currently viewing. Printing does not occur by simply pressing the "P" key, so feel free to explore this option without worry of wasting your paper and ribbon. ~* Printing Definition Screen ----------------------------------- BUZ allows a great deal of versatility for printing out text files. Its main emphasis is on allowing partial printouts of large files. For this reason the "printing definition screen" may appear a bit complicated at first. Don't hesitate to explore the available options since you can abort back to the viewer instantly. As a matter of fact, the "printing definition screen" contains a lot of useful information about the file that you are viewing. The top 1/3 of the screen contains information about the file size and just where you were currently located when you pressed the "P" key in the file viewer. It also provides information about line length and some existing control codes. The center 1/3 of the screen is a list of option keys that you can use in various ways to set up the definition of your printout. Feel free to experiment with their settings, without actually starting a printout. It will not start printing without a confirmation from you. Even with a blind confirmation, the default is to print out only 1 page - you must choose an option to be able to print more then 1 page. The bottom 1/3 of the screen (inside of the box), is the active definition for your printout. It is a summary of the parameters for the printout. Any input requests will also occur in this box (except for the title). Below are your option keys for defining the printout: ~ Complete File ------------------------- Pressing the "A" key specifies the entire file from beginning to end. ~ Current Top Line to End ----------------------------------- Pressing the "B" key specifies printing the top line of the screen to the end of the file. "Current Top Line" refers to the line at the top of the file viewer screen when you pressed the "P" key for the print option. ~ Current Section --------------------------- Pressing the "C" key sets the printing definition to print that section of an indexed file that you were viewing when you entered the "printing definition screen". It begins at the index marked line and ends with the line before the next index marker in the file. The "current section" title appears above and you should check that it is what you actually wish to printout. If more than one index marked section was on the screen at the time that you chose "print", the last one on the screen is treated as the current section. The "D _ Down one section" and "U _ Up one section" options allow you to adjust the "current section" by one index marked section. If the file being viewed contains no section definitions, neither the option keys nor the section information will appear in the printing definition screen. ~ Change Printer Port ------------------------------- The "P" key is a selector key to specify where the printing output is to be sent. The "Printing to:" setting in the definition box changes each time that the "P" key is pressed. You can send your printout to LPT1, LPT2, LPT3, COM1, COM2, COM3, COM4, or to a FILE. The default setting is LPT1. Be sure that any LPT or COM specification is actually a printer, or you may cause an error to BUZ (and DOS) that will land you back on the DOS command line! The "print to a file" capability of BUZ may at first seem redundant, but it is actually a very versatile option. Specifying a portion of a large file can allow you to clip out a portion for a text editor with limited capacity. When you "print to a file" the tilde markers are automatically striped out. You have the option to print with headers and page breaks, so you can instantly create a "printer page formatted" file if you have a need for one. A few things to keep in mind about the "print to a file" option: 1. All tilde markers are normally striped out. ONLY tilde markers are striped out. Any /MSB, /C, /AL, /PAS comment based markers are NOT removed. (Note: To preserve the tilde markers in a normal "prepared for BUZ" file, load the file using the /AL command line option. Also be sure that "Indent" is set to zero.) 2. All pre-existing form feed characters in the file are striped out. 3. If the text was shifted to the right on the screen, check to see if "Indent" is set at 3 by default. BUZ automatically indents suitable files (ones that have no lines over 76 characters in length) by 3 spaces. Use the "Indent" setting to adjust if needed. 4. Printer page formatting with headers and page breaks is set for standard 66 line by 80 character pages by default. The headers will be just like a standard BUZ printout. Since each BUZ printed page ends with a FormFeed, "Lines per Page" can be used to control the amount of blank lines left at the end of each page. A smaller number yields more blank lines. 5. Any "TAB#" setting that is in effect, will be reflected in the "print to a file" output. (You can use this feature to strip or replace ^I tabs with spaces in some files.) 6. Any line wraps from line lengths over 80 characters, will not be "hard wraps" in the output file. They will still be their original length. ~ Wrap Tracking for 80 -------------------------------- When Wrap Tracking 80 is [Yes], BUZ will count any lines over 80 characters as 2 lines to keep the page lengths corrected. It takes into account the "Indent" value as well. It also prevents the header from wrapping if you "Indent" beyond 5. If you are printing on an 80 character/line printer, leave "Wrap Tracking 80" set to [Yes]. If you are printing in condensed mode (132 or 160 character lines) or on a wide printer, set Wrap Tracking 80 to [No]. Condensed mode and Wrap Tracking 80 [No], is the best way to print files that have lines over 80 characters. The "Max. Line Length" plus the "Indent" setting will indicate the best printing approach for a particular file. If "Max. Line Length" + "Indent" exceeds 80, then some lines WILL wrap on 80 character/line printers. The "Max. Line Length" value is the length of the longest line found in the file. ~ Specify the Top Line -------------------------------- Pressing the "1" option allows you directly input the line number of the file where the printout is to begin. ~ Specify # of Lines to Print --------------------------------------- Pressing the "2" option allows you to directly input the number of lines (starting with the defined top line) that will be printed out. ~ Specify # of Pages to Print --------------------------------------- Pressing the "3" option allows you to directly input the number of pages (starting with the defined top line) that will be printed out. The "Pages" referred to here will be defined by the "Page Formatting" and "Lines per Page" settings that are in effect. Set the "Page Formatting" and "Lines per Page" options before specifying the number of pages. If your file contains long lines that "wrap", the page estimates may be under the actual number, but the printouts WILL format out properly. ~ Left Indent ----------------------- This setting is the number of blank spaces in front of each line that is printed. There are two defaults: It is set to 3 if there are no lines over 76 characters in the file, or it is set to zero if the file contains any longer lines. You can set the indent to anything that you wish, but you should do it with caution. Printers will wrap lines that are longer then what they can print in a single line. The wrapped portion of any line will begin on the next line - without any indentation. If "Wrap Tracking for 80" is [Yes], BUZ will at least prevent most page overflows on 80 character/line printers. The maximum allowed Indent value is 85 when "Wrap Tracking for 80" is [Yes]. The appearance of indented with wrapped lines is usually not very neat, with one exception - double spaced printouts. By setting the indent to the number of characters/line supported by your printer, you will get a neat double spaced printout. A double spaced printout should either have "Page Formatting" set [No] or be done as follows: 1. Be sure "Max. Line Length" is not over 80; 2. Be sure your printer is in 80 character/line mode; 3. [Yes] for both "Page Formatting" (or [Lite]) and "Wrap Tracking 80"; 4. Set the indent value to 80 (plus upto 5 if "Max. Line Length" is 75 or less). Note: The "Pages" estimates will be 1/2 of the actual number of printed pages when you double space using Indent. The "Max. Line Length" value is provided to assist with indenting printouts properly. Its value is the length of the longest line in the file. You can therefore indent by as many spaces as your printer can handle, in addition to the longest line. "Indent" + "Max. Line Length" should not exceed the character/line abilities of your printer. If your printer allows 160 and/or 132 character Condensed printing, you can set your printer, and indent considerably. When doing printing in condensed modes (or on wide printers) be sure to set "Wrap Tracking for 80" to [No]. (Be aware that BUZ cannot set your printer to condensed mode nor can it detect that it is set as such.) The indent value affects both the text and the headers. If "Wrap Tracking for 80" is [No], the headers are always indented as much as the text. If "Wrap Tracking for 80" is [Yes], then the headers will only indent to 5 spaces maximum. You can indent the text further, but the headers remain at 5 to prevent them from being wrapped or cropped. ~ Page Formatting --------------------------- "Page Formatting" [Yes], means that the output will have an informative header on each page, and have a few blank lines at the bottom of each page. "Page Formatting" [No], means that the output will be continuous without any headers or page-break blank lines. When you change this setting, all page estimate values will be adjusted accordingly. "Lines per Page", "Wrap Tracking for 80", "Change Title" and "Left Indent" settings have relevance to page formatting that is discussed in each section. The headers on each page contain 5 areas of information: 1. A custom defined title that is constant on each page. See the "Change Title" section about defining it. 2. A date is printed. This is the date (per your computer) that the printout was made. It is not the directory date associated with the file being printed. 3. "From line ###" Reports what line in the file that the printing began with. 4. "p#" is the sequence page of the printout. It starts with 1 on the first page, then 2 on the second, etc. 5. The file name that the printout originated from is printed on each header. It is only the basic file name without any preceding path. When "Page Formatting" is [Yes], 11 lines are used per page for the formatting; 7 for the header, and 4 for page breaks. See the "Lines per Page" section for variations that affect the page break spaces. "Page Formatting" [ Lite ] is the same as [ Yes ] except that the header contains only the Title and page number. It was included for those printouts that you do not want much if any header, but need the page breaks. Making the Title blank will further reduce the header to only the page number and header base line. If you then increase the "Lines per Page" to 68 and roll back the paper a bit, you will have an uncluttered printout with little more than page breaks. ~ Change Title ------------------------ Any printout by BUZ can be formatted with headers and page breaks, or not. The top line of each formatted printed page has a constant custom defined title. By default, the file's title line is used (if there is one). If you wish to enter a new title, press "T" and type it in using standard editing keystrokes as needed. If you want to clear the line and start again, press Escape. Press Enter when you are done. The title will only be used if "Page Formatting" is [Yes] or [Lite]. The maximum number of printable characters is 70. You can type in more than 70, but they will be cropped off in the printout. ~ Lines per Page -------------------------- The "Lines per Page" setting is used to define how many lines your printer can print per page. Most tractor feed printers have 66 line pages, which is the default setting. Sheet feed printers may have less, perhaps 60. For the actual printout, this setting is only relevant when "Page Formatting" is [Yes] or [Lite]. This setting is also used for the number of page calculations that are displayed on the printing definition screen. The "Lines per Page" setting can also be used to customize the way that your printout will format. When the proper number of lines has been counted by BUZ, it sends a Form Feed to your printer, and begins printing on the next page (as defined by your printer). The Header printed by BUZ, uses 7 lines on each defined page. Text is then printed until 4 lines are remaining (or the end of the defined printout), and then a Form Feed is sent. This is the default for 66 line pages. By setting "Lines per Page" to a lower number, you can increase the number of blank lines on the end of each page. If you want a no-page-break printout with only one leading header, you can set "Lines per Page" to the total number of lines to be printed - plus 11 (or more) to allow for the header and ending blank lines. The accuracy of your setting can be confirmed by checking that the "# of Pages:" indicates just 1. If you can very accurately align the pages on your printer, you can set it to 68 and save an occasional sheet of paper. Don't set for less then 2 ending blank lines per page, since BUZ may print an extra line under some circumstances. If a page overflow occurs, there will be blank pages and/or pages that are only partially filled. ~ Filename for Output ---------------------------- If you are printing-to-a-file, the final question will be to provide a filename. The top of your screen will become a directory listing of your current directory and drive. The filename that you supply can be preceded by a path specifying a different directory, but you will not be able to preview the contents of that directory. If the filename that you enter already exists, you will be asked if it is alright to overwrite it or not. If you answer "N" no, the print-to-a-file will be aborted. ~* Creating a "Prepared for BUZ" Text File ------------------------------------------ Preparing an existing text file for indexed viewing is extremely simple. All that needs to be done is to insert a tilde ~ character into the first character position of lines that are to be used as index markers. It is important that the tilde character be the very first character. If a space or other character precedes it in the line, it will not be interpreted as a marker. Since BUZ has no editing capabilities, you will need to use a text editor to insert the tilde markers. If you use a word processor, be sure that it is used in the ASCII mode, so that its document mode formatting and control codes are not embedded into the file. The first 2 lines marked by a tilde are for the title and author credits. They are used only for display purposes, and are not actually placed into the index list. If you do not want a title or author line, place the first 2 tilde markers on leading blank lines. The third tilde marker is the first actual index marker. All tilde marked lines, beginning with the third, will be included into the index table as reference lines. Any number of tilde marked lines are allowed - up to the maximum of 360 (20 index screen pages). Any tilde marked lines exceeding the maximum are ignored by BUZ. The marked lines appear in the index table in same order that they are in the file - from top to bottom. Typically the marked lines would be chapter or section titles, but any line can be marked for index use. Note that the entire marked line appears in the index, so marked lines should not exceed 75 characters in length. (They will be cropped if they are over 75.) When lines marked by a tilde are displayed or printed out by BUZ they will not include the tilde itself. Leading tilde characters are striped from the lines of text before display or printing. Of course, if a "prepared for BUZ" file is viewed or printed by another utility, the tilde markers will be visible. If you wish to create a copy of the prepared text file with the tilde markers removed, just have BUZ print-to-a-file the entire text file. Other than the tilde insertions, there are no other special formatting requirements for standard ASCII text files. Any file that displays properly by using the DOS "TYPE" or "MORE" commands will generally work well with BUZ. For best appearances, it is recommended that the line length be limited to 75 characters (not including the tilde markers). BUZ will wrap lines that are over 80 characters in length, but the results will not be very appealing. Extremely long lines (over 160 characters) are likely to cause problems for BUZ. Embedded control codes in a text file may create problems. BUZ stripes out any existing ^L (formfeed) codes for screen and printer output and expects lines to end with a standard carriage return-line feed. It is not designed to deal accurately with some control codes, such as lone ^J (line feed) insertions. The presence of these types of codes is not always clearly visible, but they may cause odd screen rolls by the BUZ file viewer. Embedded ^I (tab) characters may cause problems in lines over 80 characters long. For best results, remove any non-standard control codes from text files intended to be viewed with BUZ. The file viewer will accurately display all ASCII characters from decimal #32 through #254. That includes all of the normal upper ASCII graphics characters. Whether the graphics characters print properly, will depend on if the printer can interpret them. Some of the ASCII characters below #32 (control codes) appear to work in the BUZ viewer, but should not be used since they have special meanings to printers. Sending unplanned control codes to a printer can produce all kinds of havoc in printouts. ~ Highlighting lines of text -------------------------------- BUZ will automatically highlight any line of text that has the leading tilde marker character. (It will do this regardless of whether the file was intentionally "index prepared" or not.) To allow emphasis in the index table, a tilde followed by an asterisk ~* , will cause that line to be highlighted in both the index table and the file. The asterisk character IS displayed on the screen and on any printouts. ~ The /MSB /C /AL and /PAS Command Line Options for Source Code ------------------------------------------------------------------- BUZ is equipped to give indexed viewing of properly formatted source code files for Microsoft BASIC (and Quick BASIC), "C", Assembler, Lisp (and AutoLisp), and Pascal programming languages. Of course the desired file must be in the original ASCII text format, not compiled or in a binary format. When /MSB is used, BUZ ignores tilde character and indexes on the ' single quote character (the BASIC comment line character) instead. To be a qualifying index line, the single quote must be the very first character on that line. Any indented comment lines are not treated as index marked lines, so it is a simple process to qualify certain comment lines for index usage. Unlike the default tilde markers, the leading single quote character is both displayed and printed. The /C, /AL, and /PAS options are identical to /MSB except that the index character is / slash for /C, ; semicolon for /AL, and { the left curly bracket for /PAS (the leading comment area/line characters for programming source code). [ If you program in another language, and this feature sounds appealing - send me a sample of source code (with some comment lines included) and I will try to include an appropriate switch in the future. ] Source code files typically contain lines over 80 characters. These long lines cause BUZ to wrap them to the next screen line. This can cause some minor aberrations in the viewer's scrolling. It is accurate in the Page Up-Down scrolling, but the Line Up-Down scrolling can "skitter" a bit from the wrapped lines. What is displayed on the screen is accurate, but the wrapped lines can cause a slight jump (a few lines) in file location under some circumstances. This slight jump is most likely to occur when changing from using line scrolling to using page scrolling. The printouts ARE quite accurate, with long lines being wrapped as needed. For most printouts of source code, it is recommended that you switch your printer to condensed mode if it has the capability. That will eliminate the wrapping of longer lines. (See the "Wrap Tracking for 80" section. ~ Creating and Using BUZ Quick Index files ---------------------------------------------- By default BUZ creates an index on-the-fly for valid files. Creating this index requires it to parse through every line of the file before you can begin viewing. This can take a fair amount of time with large files. BUZ can create a copy of the index and save it to disk and then, in future viewings, read it instead of the entire file. The use of a BUZ Quick Index file will typically allow you to begin viewing in 1/2 or less of the normal startup time. (This is a hard drive speed enhancement feature. It is disabled while reading a file on the A: or B: drives. Creating a Quick Index on a floppy will only waste disk space.) Creating a BUZ Quick Index is as simple a key press! While in the index screens, press the X key and a BUZ Quick Index file will be created and saved to disk in the same directory as the text file that you are viewing. The BUZ Quick Index file has the same name as its associated text file except that the first character of the extension is replaced by the right curly bracket character "}". The next time that you view your current file, BUZ will find the Quick Index file and read it instead of parsing the entire file. If you edit or change a text file that has an associated Quick Index file, BUZ will know this and not use it. As a matter of fact, BUZ will automatically try to delete any Quick Index that no longer matches its associated text file. It then switches to its default of parsing through the entire file. It is up to you to create a new Quick Index if you want one. If you see the index table being built line-by-line, you know that there is not a valid Quick Index being read. If you create a BUZ Quick Index file for a source code file (loaded with the /C /MSB /AL or /PAS command line option switch), you will not need to use the command line switch to view it the next time. BUZ saves the switch information in the Quick Index. BUZ Quick Index files are completely optional. For smaller text files on fast computers, they are probably a waste of disk space. For very large text files and/or on slower computers, you'll probably want to use them for any files that you will want to view more than a time or two. You can safely delete any Quick Index files any time - nothing is lost that cannot be quickly and easily replaced. (Note: Quick Indexes are NOT read if the file is on the A: or B: drive) ~ Example of File Preparation --------------------------------- Below is an illustration of how "Prepared for BUZ" text files were intended to be formatted. +----------------------------------------------------------------+ | | |~* Title | | | |~ Author Credits | | | | | |~* Chapter 1 | | | | text | | text | | text | | | |~ Sub Section | | | | text | | text | | text | | | |~* Chapter 2 | | | | etc. | +----------------------------------------------------------------+ ~* Become a registered BUZ user! -------------------------------- BUZ.EXE is Shareware. BUZ.EXE may be shared with others so long as it is accompanied by BUZ.DOC and both files remain unaltered. BUZ is intended to be a try-before-you-buy program. It is not FREEware. If you like BUZ and use it - please register and pay for it. NOTICE: BUZ.EXE may only be distributed in the United States and Canada, unless you get written permission from the author - Dan Jincks. No exceptions! BUZ.EXE was developed to fill a text file viewing need in my other shareware products. It turned out so well that I expanded it into a more powerful general purpose program. If you are a paid registered user of any other program by Dan Jincks, you need not pay for BUZ.EXE 1.10 - you are automatically considered registered. ~ Basic User Registration ----------------------------- If you are not a paid registered user of another program by Dan Jincks, and you like and use BUZ.EXE 1.10, you are requested to register as a "basic user" and pay a small fee. Your registration will be valid for any future upgrades that you acquire on your own, until the author requests you to pay an upgrade fee in the new version documentation. (not expected until version 2.00 or later) The fee is very small, and as such, the author offers no "extras" for registering. If you like it as-is, please buy it. ~ Distributing User Registration ------------------------------------ If you are a Shareware or Freeware author, and would like to include BUZ.EXE 1.10 with your product, you should register as a "distributing user" and pay a modest "distributing user" registration fee. Then you may distribute BUZ.EXE with your Shareware or Freeware - but BUZ.DOC must accompany it in a very obvious manner. You may not alter BUZ.EXE or BUZ.DOC, or attempt to hide its exit message and copyright notices. You also must make it clear that BUZ.EXE is unregistered Shareware which requires a separate "basic user" registration fee if used regularly. The "distributing user" registration is more expensive than the "basic user" registration. This is not the act of selling you a distributing license. The extra charge is so that I can keep records and supply you with upgraded versions as they become available. Record keeping and shipping disks costs more than the "basic registration" fee. You are encouraged to critique the way that BUZ.EXE does or does not fill your needs. You are welcome to suggest improvements - and your ideas will be given serious consideration in developing future improvements. Sending me a copy of your applied usage of BUZ.EXE is optional, but recommended. This is so that I can tailor improvements properly. ~ Commercial Distribution ----------------------------- If you are interested it using BUZ.EXE 1.10 in or with a commercial software product, I am flattered! Contact me directly to negotiate a very reasonable arrangement. BUZ.EXE may NOT be utilized in any commercial (paid for) products without a written contractual agreement with Dan Jincks. ~ Retail Computer System and Software Dealers ------------------------------------------------- You are welcome to distribute BUZ.EXE under the same conditions as the "Distributing User" as outlined above. You may not charge your customers for BUZ.EXE in any manner, or you are a "commercial distributor" and MUST negotiate a contractual arrangement. ~ Shareware Distributors ---------------------------- You may distribute BUZ.EXE 1.10 in a way that is consistent with the other Shareware products that you offer (ASP standards or better). If you actually utilize BUZ.EXE for your marketing or distribution in any manner, (e.g. Shareware catalog on disk) you must adhere to the rules of a "distributing user", and register as such. (To Print: Press "P" ENTER "Y") ~* Registration Form for BUZ.EXE V1.10 -------------------------------------- Basic User Registration ____________ first 5 computers - $5 per computer 6th to 100th computer - $4 per computer over 100th computer - $3 per computer Registration fee amounts should be based on the total number of computers that BUZ.EXE is installed on, or used on, for any one address or company. Distributing User _ (See the above conditions) __________ $30 per address Type of registration ______________ Number ______ Amount ______________ Company Name ____________________________________________________________ Name ____________________________________________________________________ Address _________________________________________________________________ City, State and Zip _____________________________________________________ Where did you acquire BUZ? ______________________________________________ Send a Check or Money Order to: Dan Jincks HCR 77, Box 155A Annapolis, MO 63620 USA Notice: BUZ.EXE is distributed AS-IS. The user accepts full responsibility for the suitability and usage of BUZ.EXE. In no manner may the author, Dan Jincks, be held liable for any damages that may allegedly occur from the use of BUZ.EXE. *********************************************************************** BUZ.EXE is dedicated to preserving our tree resources. Hopefully a few trees will live a longer life (and continue purifying the air), due to the capabilities of BUZ. Use BUZ to reduce your printer paper consumption whenever you can. Dan